Crate rtnetlink

This crate contains building blocks for the route netlink protocol.

Messages

This crate provides two representations of most netlink packets:

• Buffer types: NetlinkBuffer, LinkBuffer, NlaBuffer, etc. These types wrappers around actual byte buffers, and provide safe accessors to the various fields of the packet they represent. These types are useful if you manipulate byte streams, but everytime data is accessed, it must be parsed or encoded.

• Message and Nla types: NetlinkMessage, LinkMessage, LinkNla, AddressNla etc. These are higher level representations of netlink packets and are the prefered way to build packets.

Using buffer types to parse messages

It is possible to go from on representation to another. Actually, the buffer types are used to parse byte buffers into messages types, using the Parseable trait. In the list of implementors, we can see for instance:

impl<'buffer, T: AsRef<[u8]> + 'buffer> Parseable<NetlinkMessage> for NetlinkBuffer<&'buffer T>

That means a NetlinkBuffer is parseable into a NetlinkMessage:

extern crate rtnetlink;
use rtnetlink::{NetlinkBuffer, NetlinkMessage, Parseable};
use rtnetlink::constants::{RTM_GETLINK, NLM_F_ROOT, NLM_F_REQUEST, NLM_F_MATCH};

// a packet captured with tcpdump that was sent when running `ip link show`
static PKT: [u8; 40] = [
    0x28, 0x00, 0x00, 0x00, // length
    0x12, 0x00, // message type
    0x01, 0x03, // flags
    0x34, 0x0e, 0xf9, 0x5a, // sequence number
    0x00, 0x00, 0x00, 0x00, // port id
    // payload
    0x11, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x08, 0x00, 0x1d, 0x00, 0x01, 0x00, 0x00, 0x00];

fn main() {
    let pkt: NetlinkMessage =
        // Create a buffer. Notice the double &&. That is because Parseable<NetlinkMessage> is
        // implemented for NetlinkBuffer<&T> not NetlinkBuffer<T>. The reason behing this is
        // that we want the storage T to be able to outlive our NetlinkBuffer, if necessary. It
        // feels a bit weird here but can be useful in other circumstances.
        NetlinkBuffer::new_checked(&&PKT[..])
            .unwrap()
            // Convert the buffer into an actual message. This is when the parsing occurs.
            .parse()
            .unwrap();

    println!("{:#?}", pkt);
}

This prints:

NetlinkMessage {
    header: NetlinkHeader {
        length: 40,
        message_type: 18,
        flags: NetlinkFlags(769),
        sequence_number: 1526271540,
        port_number: 0
    },
    message: GetLink(
        LinkMessage {
            header: LinkHeader {
                address_family: 17,
                index: 0,
                link_layer_type: Netrom,
                flags: LinkFlags(0),
                change_mask: LinkFlags(0)
            },
            nlas: [ExtMask(1)]
        }
    ),
    finalized: true
}

Emitting messages

TODO

Should I use Buffer types or Message type (NetlinkBuffer or NetlinkMessage)?

Message types are much more convenient to work with. They are full blown rust types, and easier to manipulate. I use buffer types mostly as temporary intermediate representations between bytes and message types.

However, if you have to treat large quantities of packets and are only interested in a few of them, buffer types may be useful, because they allow to perform quick check on the messages without actually parsing them.

TODO

Tokio integration

TODO

Modules

constants

Structs

AddressBuffer
AddressCacheInfo
AddressHeader
AddressMessage
DefaultNla
ErrorBuffer
ErrorMessage
LinkBuffer
LinkFlags
LinkHeader	High level representation of RTM_GETLINK, RTM_SETLINK, RTM_NEWLINK and RTM_DELLING messages headers.
LinkIcmp6Stats
LinkInet6CacheInfo
LinkInet6DevConf
LinkInet6Stats
LinkInetDevConf
LinkMap
LinkMessage
LinkStats
NetlinkBuffer	A raw Netlink buffer that provides getters and setter for the various header fields, and to retrieve the payloads.
NetlinkFlags	Represent the flags field in a netlink packet header.
NetlinkHeader	A Netlink header representation.
NetlinkMessage	Represent a netlink message.
NlaBuffer
NlasIterator	An iterator that iteratates over nlas without decoding them. This is useful when looking for specific nlas.
RouteBuffer
RouteCacheInfo
RouteFlags
RouteHeader
RouteMessage
RouteMfcStats

Enums

AddressNla
Error	The error type for the netlink packet parser
LinkAfInet6Nla
LinkAfInetNla
LinkAfSpecNla
LinkInfo
LinkInfoBridge
LinkInfoData
LinkInfoKind
LinkInfoVlan
LinkLayerType
LinkNla
LinkState
RouteKind	Route type
RouteMetricsNla
RouteNla
RouteProtocol	Route origin
RouteScope	Distance to the destination
RouteTable	Routing table
RtnlMessage

Constants

ADDRESS_HEADER_LEN
LINK_HEADER_LEN
NETLINK_HEADER_LEN	Length of a Netlink packet header
ROUTE_HEADER_LEN

Traits

Emitable	A type that implements Emitable can be serialized.
Nla
Parseable	A Parseable type can be used to deserialize data into the target type T for which it is implemented.

Type Definitions

AckMessage
LinkStats32
LinkStats64
Result